futoin-hkdf
Advanced tools
RFC5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
The futoin-hkdf npm package is a JavaScript implementation of the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869. It is used to derive one or more cryptographic keys from a source key material in a secure manner.
Basic HKDF Derivation
This code demonstrates the basic usage of the futoin-hkdf package to derive a cryptographic key from initial keying material (IKM) using optional salt and info parameters.
const hkdf = require('futoin-hkdf');
const crypto = require('crypto');
const ikm = crypto.randomBytes(32); // Initial Keying Material
const salt = crypto.randomBytes(16); // Optional salt
const info = Buffer.from('info'); // Optional context and application specific information
const length = 32; // Length of the derived key
const hash = 'sha256'; // Hash function to use
const derivedKey = hkdf(ikm, length, { salt, info, hash });
console.log(derivedKey.toString('hex'));HKDF with Different Hash Functions
This code demonstrates how to use different hash functions (SHA-512 and SHA-1) with the futoin-hkdf package to derive cryptographic keys.
const hkdf = require('futoin-hkdf');
const crypto = require('crypto');
const ikm = crypto.randomBytes(32); // Initial Keying Material
const salt = crypto.randomBytes(16); // Optional salt
const info = Buffer.from('info'); // Optional context and application specific information
const length = 32; // Length of the derived key
// Using SHA-512 hash function
const derivedKeySHA512 = hkdf(ikm, length, { salt, info, hash: 'sha512' });
console.log(derivedKeySHA512.toString('hex'));
// Using SHA-1 hash function
const derivedKeySHA1 = hkdf(ikm, length, { salt, info, hash: 'sha1' });
console.log(derivedKeySHA1.toString('hex'));The futoin-hkdf package is a JavaScript implementation of the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869. It is used to derive one or more cryptographic keys from a source key material in a secure manner.
The crypto module in Node.js provides cryptographic functionality that includes a set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions. It includes an implementation of HKDF, but it is more general-purpose and not as focused on HKDF as futoin-hkdf.
The hkdf package is another implementation of the HKDF algorithm in JavaScript. It provides similar functionality to futoin-hkdf but with a different API. It is also focused solely on HKDF and provides a simple and straightforward interface for key derivation.
Node.js implementation of RFC5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
Additionally, it supports a HKDF-Expand-Label variation based on RFC8446: The Transport Layer Security (TLS) Protocol Version 1.3, section 7.1. Key Schedule.
The implementation is fully compliant with test vectors provided in the RFC.
There are alternative modules, but they are:
Standalone HKDF extract() and expand() actions are also available for advanced usage.
Documentation --> FutoIn™ Guide
Author: Andrey Galkin
The figures in "derived keys per second".
node-hdkf/hdkf modules - 57 707 (~22% slower)
ctrlpanel-hdkf - 52 181 (~30% slower)
@stablelib/hkdf - 39 808 (~46% slower)
Command line:
$ npm install futoin-hkdf --save
or:
$ yarn add futoin-hkdf --save
const hkdf = require('futoin-hkdf');
// Parameter overview
//-------------------
// initial keying material
const ikm = 'string-or-buffer';
// required output length in bytes
const length = 16;
// can be empty string or false equivalent
const salt = 'strongly-encouraged';
// optional parameter
const info = 'optional-context';
// HMAC hashing algorithm to use
const hash = 'SHA-256';
// Generic derivation
//-------------------
hkdf(ikm, length, {salt, info, hash}); // Buffer(length) - derived key
hkdf(ikm, length, {salt, info, hash}).toString('hex'); // String(2*length)
// NOTE: all optional paramaters are passed in object
// With some parameters omitted
//-------------------
hkdf(ikm, length, {salt});
hkdf(ikm, length, {info});
hkdf(ikm, length, {hash});
hkdf(ikm, length);
// Advanced usage (only if you know what you are doing)
//-------------------
// As in underlying Node.js crypto library
const lhash = hash.toLowerCase().replace( '-', '' ); // 'sha256'
hkdf.hash_length(lhash); // get hash_len
hkdf.extract(lhash, hash_len, ikm, salt); // run only step #1
hkdf.expand(lhash, hash_len, prk, length, info); // run only step #2
// TLS v1.3+
//-------------------
const hkdf_tls = require('futoin-hkdf/tls');
const label = 'tls13 ...';
const context = Buffer.from( /* E.g some binary hash generation */ '' );
hkdf_tls(ikm, length, {salt, label, context, hash}); // Buffer(length) - derived key
// Advanced usage
hkdf_tls.expand_label(lhash, hash_len, prk, length, label, context);
// Same as:
hkdf.expand(lhash, hash_len, prk, length, hkdf_tls.info(length, label, context));
BufferHMAC-based Extract-and-Expand Key Derivation Function (HKDF)
BufferTLS v1.3 HKDF-extract + HKFD-Expand-Label action
BufferHMAC-based Extract-and-Expand Key Derivation Function (HKDF)
Kind: global function
Returns: Buffer - Raw buffer with derived key of @p length bytes
| Param | Type | Default | Description |
|---|---|---|---|
| ikm | Buffer | string | Initial Keying Material | |
| length | integer | Required byte length of output | |
| salt | Buffer | string | '' | Optional salt (recommended) |
| info | Buffer | string | '' | Optional context (safe to skip) |
| hash | string | "'SHA-256'" | HMAC hash function to use |
Buffer
integerBufferBufferintegerGet expected hash length.
Kind: static method of hkdf
Returns: integer - hash digest byte length
Note: Values are hardcoded with fallback for unknown algorithms.
| Param | Type | Description |
|---|---|---|
| hash | string | Hash algorithm (as in underlying Node.js crypto library) |
BufferHKDF extract action.
Kind: static method of hkdf
Returns: Buffer - A buffer with pseudorandom key
Note: Values are hardcoded with fallback for unknown algorithms.
| Param | Type | Description |
|---|---|---|
| hash | string | Hash algorithm (as in underlying Node.js crypto library) |
| hash_len | integer | Hash digest length |
| ikm | Buffer | string | Initial Keying Material |
| salt | Buffer | string | Optional salt (recommended) |
BufferHKDF expand action.
Kind: static method of hkdf
Returns: Buffer - A buffer with output keying material
Note: Values are hardcoded with fallback for unknown algorithms.
| Param | Type | Description |
|---|---|---|
| hash | string | Hash algorithm (as in underlying Node.js crypto library) |
| hash_len | integer | Hash digest length |
| prk | Buffer | string | A buffer with pseudorandom key |
| length | integer | length of output keying material in octets |
| info | Buffer | string | Optional context (safe to skip) |
BufferTLS v1.3 HKDF-extract + HKFD-Expand-Label action
Kind: global function
Returns: Buffer - Raw buffer with derived key of @p length bytes
Note: label and context are limited to 255 bytes!
| Param | Type | Default | Description |
|---|---|---|---|
| ikm | Buffer | string | Initial Keying Material | |
| length | integer | Required byte length of output | |
| salt | Buffer | string | '' | Optional salt (required by fact) |
| label | Buffer | string | '' | Optional label (required by fact) |
| info | Buffer | string | '' | Optional context (safe to skip) |
| hash | string | "'SHA-256'" | HMAC hash function to use |
BufferEncode HKDF context parameter in TLS v1.3 style based on RFC8446 TLS v1.3.
Kind: static method of tls
Returns: Buffer - A buffer with encoded HKDF context
Note: label and context are limited to 255 bytes!
| Param | Type | Description |
|---|---|---|
| length | integer | length of output keying material in octets |
| label | string | ASCII label |
| context | Buffer | string | Binary context or empty string |
BufferTLS-HKDF expand label action - a HKDF-Expand-Label variation based on RFC8446 TLS v1.3.
Kind: static method of tls
Returns: Buffer - A buffer with output keying material
Note: label and context are limited to 255 bytes!
| Param | Type | Description |
|---|---|---|
| hash | string | Hash algorithm (as in underlying Node.js crypto library) |
| hash_len | integer | Hash digest length |
| prk | Buffer | string | A buffer with pseudorandom key |
| length | integer | length of output keying material in octets |
| label | string | ASCII label |
| context | Buffer | string | Binary context or empty string |
FAQs
RFC5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
The npm package futoin-hkdf receives a total of 402,866 weekly downloads. As such, futoin-hkdf popularity was classified as popular.
We found that futoin-hkdf demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.